Quick Links

Standard Properties - Simple key/value pairs
System Properties - Using system properties
Container Properties - Setting objects as properties from a container such as Jndi or Spring
Map Properties - Defining property maps
List Properties - Defining property lists and arrays
File Properties - Loading properties from file
Text Properties - Embedding Scripts and Xml in your configuration
Factory Properties - Using Object factories to create properties
Property Placeholders - Using variables

Mule Properties

Most of the configuration elements in the Mule Xml configuration can have a <properties> element. This defines a set of bean properties that will be set on an object using standard getters and setters. As such, the properties names themselves must follow the JavaBean naming convention where the 'get' or 'set' part of the property method is removed and the first character of the property name is lowercase. So for a bean that has a methods getTestProperty() and setTestProperty(...) the property name is testProperty.

<properties>
    <property name="testProperty" value="foo"/>
</properties>

If a property is of type boolean, int, long, double, byte or float it will be automatically converted to the correct type. Properties can also be Maps, Lists arrays,System properties, objects from a configured IoC container and factory objects. Each of these are described in more detail below.

System Properties

A property can be set as a system property i.e. a property retrievable using -

String prop = System.getProperty("prop");

To define a system property you must use the <system-property> element.

<properties>
    <system-property name="testProperty" key="TestProperty" defaultValue="foo"/>
</properties>

The name attribute refers to the name of the property on the bean, the key is the name of the property to look for in the System properties. The defaultValue provides an optional default value if the property is not set on the System properties. If the desired default value is null, just omit this attribute.

Container Properties

These are properties that are retrieved from a configured IoC or Naming container, such as Spring, Jndi or EJB. The container is configured on the root configuration element using the ≶container-context> element. See Object Containers for more information.

<properties>
    <container-property name="testProperty" reference="testBean" required="true" container="jndi"/>
</properties>

Factory Properties

Factory properties allow a property attribute to be created using a factory object. For example, in testing you might want a property factory to create an InitialContext to save setting up Jndi. A property factory must implement org.mule.config.PropertyFactory. This interface has a single method create with a java.util.Map parameter that is a map of all the properties contained within the current <properties> element. So you can configure properties for the factory instead of the bean itself if required.

<properties>
    <factory-property name="testProperty" factory="org.foo.MyPropertyFactory"/>
</properties>

Configuring Maps

Maps can be expressed in a properties element using the &lt:map> element. The name of the property is specified as an attribute of the element and each property entry below will be added to the map.

<properties>
    <map name="testMap">
        <property name="testProperty1" value="foo"/>
        <property name="testProperty2" value="bar"/>
    </map>
</properties>

A map element can contain all types of property elements listed above.

<properties>
    <map name="testMap">
        <container-property name="testProperty1" reference="foo"/>
        <system-property name="testProperty2" value="bar"/>
        <factory-property name="testProperty3" value="org.foo.TestFactory"/>
        <property name="testProperty4" value="test4"/>
    </map>
</properties>

Configuring Lists

Lists and Arrays are configured in the same way, in that there is not difference in configuring an array or list in the configuration file, when the property is set it will be converted to a List or array depending on the expected type.

<properties>
    <list name="testList">
        <entry value="foo"/>
        <entry value="bar"/>
    </list>
</properties>

You can configure list entries as container, factory or system properties by using the 'container-entry', 'factory-entry' and 'system-entry' respectively.

<properties>
   <list name="propertiesList">
        <factory-entry factory="org.mule.tck.testmodels.mule.TestDependentObject"/>
        <container-entry reference="Apple" required="true"/>
        <system-entry key="os.version"/>
        <entry value="test1"/>
    </list>
</properties>

Loading properties from a file

You can load properties for any object from a Java .properties file by using the 'file-properties' element. This will load a properties file from the classpath or file system. You can also specify an 'override' property that if set to true will over write any properties already configured on the object. The default for 'override' is true.

<properties>
   <file-properties location="org/foo/some.properties" override="false"/>
</properties>

Text Properties

You can load a blob of text as a property string inside a Mule Xml Configuration file. This text can be an embedded script, Xml, Xsl or any other type of text string. If embedding Xml you need to wrap the text in a CDATA block. For example, to embed xml -

<properties>
    <text-property name="configuration">
        <![CDATA[
        <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" 
                  "http://www.springframework.org/dtd/spring-beans.dtd">
            <beans>
                <bean id="foo" class="org.bar.Foo"/>
            </beans>
        ]]>
    </text-property>
</properties>

The CDATA block is not necessary if embedding regular text. The following example embeds a groovy script -

<mule-descriptor 
    name="GroovyUMO1"
    inboundEndpoint="vm://groovy.1"
    implementation="org.mule.components.script.jsr223.ScriptComponent">

    <properties>
        <text-property name="scriptText">
            return "Groovy Received!"
        </text-property>
         <property name="scriptEngineName" value="groovy"/>
    </properties>
</mule-descriptor>

Property Placeholders

Property placeholders can be used to substitute a property value in the Mule Xml configuration at run time. Properties can be loaded from Java .properties files and be referenced by any attribute in the Mule Xml configuration using familiar ant-style notation.

Say you have a jndi.properties file with properties in it -

jms.initial.context=org.jnp.interfaces.NamingContextFactory
jms.provider.url=jnp://localhost/
jms.connection.factory=java:/ConnectionFactory
jms.specification=1.1

These properties can then be loaded into the MuleManager properties. To load property values the Mule Xml 'environment-properties' element must be used.

<mule-configuration>
    <environment-properties>
       <file-properties location="jndi.properties"/>
    </environment-properties>
    ...
</mule-configuration>

Now you can reference the property values using property placeholders -

<connector name="jms" className="org.mule.providers.jms.JmsConnector">
    <properties>
       <property name="connectionFactoryJndiName" value="${jms.connection.factory}"/>
       <property name="jndiInitialFactory" value="${jms.initial.context}"/>
       <property name="jndiProviderUrl" value="${jms.provider.url}"/>
       <property name="specification" value="${jms.specification}"/>
    </properties>
</connector>

If a property is not found in the environment-properties the property placeholder is left intact.

Theoretically any attribute value in Mule Xml configuration can be substituted with a property placeholder. However, the mule-configuration.dtd will complain if a placeholder is used in an attribute that is an NMTOKEN or ID dtd type, such as class names. If you want to use placeholders in these fields you will have to customise the mule-configuration.dtd.